Woot woot! Lets see what @greg-1-anderson has to say.

The code looks good and I am generally +1 on this. Could you be a little more specific about what you are doing with this? Are you just renaming / re-aliasing existing commands, as the tests are doing?

My big concern here is that folks could get really confused if one module is altering commands in core or another module that is not related (in the same suite as) to the module doing the alteration.

Could you write some documentation on how this feature could be used, and also strongly encourage folks to debug log when altering commands, so that this behavior is discoverable to anyone who does get confused. It won't be possible for us to enforce logging, of course, but we can at least encourage it.

It would also be good if you could inject a logger into the woot command and debug log there, just so that the test code serves as a good example of how to alter commands. It isn't necessary to have an assert that ensures the log is printed, as long as it's there for illustrative purposes.

@greg-1-anderson, we are preparing to add migrate commands to Drush core in #3402. But we want to coordinate with migrate_tools/migrate_plus so that migrate_plus-specific migrations will still work. We will achieve this by removing the Drush commands from migrate_tools and adding command alters/replacements in migrate_plus. Now, commands are easy to replace, using hooks. For example, in migrate_plus we swap the Drush core migrate status command in this way: @hook replace-command migrate:status. But also the annotations need some changes. For example, on the same command, we have different output structure in Drush core command than in migrate_plus. The @field-labels annotation need to be swapped. So, migrate_plus module has to add some alters to some command info, too.

Perhaps some of these operations should happen automatically in annotated command. I haven't checked yet to see if this is possible / easy, but if other annotations in a @hook command-replace always completely overwrote the annotations in the hooked command, would that reduce the number of things you need to alter? Would you ever find it undesirable if @hook command-replace overwrote overlapping annotations?

@greg-1-anderson , I saw that array annotations, such as @option, @Usage are merged, not replaced. The others are kept from the original command.

LGTM thanks for contributing this - should be very useful.